.\"
.\" Copyright (c) 2016-2018  Joachim Nilsson <troglobit@gmail.com>
.\"
.\" Permission to use, copy, modify, and/or distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd Jan 3, 2018
.Dt WATCHDOGD 8
.Os "watchdogd (3.0)"
.Sh NAME
.Nm watchdogd
.Nd Advanced system & process monitor daemon
.Sh SYNOPSIS
.Nm
.Op Fl hnsVx
.Op Fl f Ar FILE
.Op Fl l Ar LEVEL
.Op Fl t Ar SEC
.Op Fl T Ar SEC
.Op Ar /dev/watchdogN
.Sh DESCRIPTION
.Nm
is an advanced system and process supervisor daemon, primarily intended
for embedded Linux and server systems.  It can monitor critical system
resources, supervise the heartbeat of processes and record deadline
transgressions before safely rebooting your system.
.Pp
When a system comes back up after a reset,
.Nm
determines the reset cause and records it in a logfile for later
analysis by an operator or network management system (NMS).  This
information can in turn then be used to put the system in an operational
safe state, or non-operational safe state.
.Sh WATCHDOG
A watchdog timer (WDT) is something most motherboards of laptops and
servers today are equipped with.  It is basically a small timer that is
connected to the reset circuitry so that it can reset the board when the
timer expires.
.Pp
The Linux kernel provides a common userspace interface
.Pa /dev/watchdog ,
created automatically when the appropriate driver module is loaded.  If
your board does not have a WDT the kernel provides a "softdog" module
which could be good enough.
.Pp
The idea is to have a watchdog daemon in userspace that runs in the
background of your system.  When there is no more CPU time for the
watchdog daemon to run it will fail to "kick" the WDT.  This will in
turn cause the WDT to reboot the system.
.Sh OPTIONS
Earlier versions of
.Nm
supported more command line options, from v3.0
.Nm
has been greatly simplified.  Use
.Xr watchdogctl 1
to query status and control
.Nm .
.Bl -tag -width Ds
.It Fl f, -config Ar FILE
Use FILE for daemon configuration.  Default:
.Pa /etc/watchdogd.conf
.It Fl h, -help
Show summary of command line options and exit.
.It Fl l, -loglevel Ar LEVEL
Set log level: none, err, info,
.Ar notice ,
debug.
.It Fl n, -foreground
Start in foreground, required when started by systemd or Finit, default is to daemonize and background.
.It Fl s, -syslog
Use
.Xr syslog 3
for log messages, warnings and error conditions.  This is the default
when running in the background.  When running in the foreground, see
.Fl n ,
log messages are printed to stdout.
.It Fl t, -interval Ar SEC
WDT kick interval, in SEC seconds, default: 10
.It Fl T, -timeout Ar SEC
HW watchdog timer (WDT) timeout, in SEC seconds.
.It Fl V, -version
Show program version and exit.
.It Fl x, -safe-exit
Disable HW watchdog (WDT) on orderly exit from
.Nm .
Not supported in all WDT drivers due to HW limitations.  Some drivers
emulate support by keeping an in-kernel thread to continue kicking the
WDT.  Make sure to try it first, or verify the WDT driver source code.
.El
.Sh SIGNALS
.Nm
responds to the following signals:
.Pp
.Bl -tag -width TERM -compact
.It TERM
Safe exit if started with the
.Fl x
flag, otherwise same as PWR.
.It INT
Same as TERM
.It PWR
Force a system reboot.  Systems with Finit use this to reboot.
.It QUIT
Same as TERM
.It HUP
Reload configuration file
.It USR1
Ignored, was used in an earlier version.
.It USR2
Same as USR1
.El
.Sh FILES
.Bl -tag -width /var/lib/watchdogd.state -compact
.It Pa /etc/watchdogd.conf
Daemon configuration file. Read once when starting up and on SIGHUP or
.Cm reload
command from
.Xr watchdogctl 1 .
.It Pa /var/lib/watchdogd.state
State pre boot, lists coming (re)boot reason.  Do not rely on the
contents of this file, it is used by
.Nm
to maintain state across boots.  If you want the status and reset cause,
read
.Pa /run/watchdogd.status
instead.
.It Pa /run/watchdogd.pid
For convenience to other processes when sending signals.  Also a useful
synchronization point, because the PID file is only created when
.Nm
is ready to receive signals and register processes with the process supervisor API
.It Pa /run/watchdogd.status
Current status, contains HW WDT status word,
.Nm
timeout and period, and the reset cause information from this boot.
.It Pa /run/watchdogd.sock
UNIX domain socket used by libwdog and
.Nm watchdogctl
to connect to
.Nm
.El
.Sh SEE ALSO
.Xr watchdogctl 1
.Xr watchdogd.conf 5
.Sh AUTHORS
.Nm
is an improved version of the original, created by Michele d'Amico and
adapted to uClinux-dist by Mike Frysinger.  It is maintained by Joachim
Nilsson at
.Lk https://github.com/troglobit/watchdogd "GitHub" .
